Summary

Documents the new status.stall.typed SSE event and its typed StallEventPayload schema introduced by PR #4806 (Issue #4802 F-9 — typed stall payload wiring at every stall-detector emit site).

What changed

• docs/api-reference.md:
  • Added status.stall.typed to the Per-Session Events (SSE) event-type list (inline reference at the top of the section).
  • Added a new Typed Stall Payload (status.stall.typed) subsection covering:
    • Full wire-format example with every StallEventPayload field populated.
    • Field reference table (typed, presence rule, description).
    • Bounded errorClass enum reference (6 values from ERROR_CLASS_VALUES).
    • Backward-compat note (legacy free-form stall event still ships in parallel).
    • Channel-fanout note (statusCode stripped for Telegram/Slack/Email via toChannelFanoutPayload()).
    • Migration recipe for consumers on the legacy stall event.

Why

PR #4806 adds a typed superset of the legacy free-form stall SSE event. The renderer (PR #4804 dashboard pill + Send continue button) consumes the typed schema, but every external consumer (CLI scripts, third-party integrations, channel transports) needs to know:

1. The new event name on the per-session SSE stream.
2. The bounded errorClass enum values (no more free-form string parsing).
3. The conditional presence of statusCode (only when errorClass === 'transient_5xx').
4. The channel-fanout fingerprint-defense rule (operator surfaces see statusCode, channels don't).

Without docs, the new event is opaque — consumers can't subscribe or render it correctly.

Aegis version

Developed with: v0.6.7

Cross-references

• Issue [dogfooding] Aegis must surface/auto-recover when CC /goal loop halts on transient 529 (upstream anthropics/claude-code#69975) #4802 (F-9 spec — typed stall payload wiring)
• PR fix(monitor): redact payload + per-session kill-switch + session_restarted (#4802) #4803 (detection-side typed contract — merged)
• PR feat(monitor): wire F-9 typed stall payload into 12 emit sites (#4802) #4806 (F-9 wiring at 12 emit sites — merged)
• PR feat(dashboard): typed stall pill + Send continue button (#4802) #4804 (dashboard typed pill + Send continue button — merged)
• src/stall-events.ts (typed contract + bounded enum)
• src/stall-detector-typed-emit.ts (emit helpers)
• src/events.ts (SessionSSEEvent union + emitStallTyped method)

Verification

• Cross-checked all field names + types against src/stall-events.ts (StallEventPayload interface, lines 56-78) ✓
• Cross-checked all 6 errorClass enum values against ERROR_CLASS_VALUES (src/stall-events.ts:35-42) ✓
• Cross-checked emitStallTyped event name (status.stall.typed) against src/events.ts:380 ✓
• Cross-checked SessionSSEEvent union addition against src/events.ts:20-22 ✓
• Cross-checked toChannelFanoutPayload strip rule against src/stall-events.ts:115-120 ✓
• Cross-checked extractStatusCode 5xx-only validation against src/stall-detector-typed-emit.ts:78-87 ✓
• Cross-checked recovery counter reset semantics against PR #4806 description (recoveryAttempts resets on success + idle transition) ✓
• Anchor link #typed-stall-payload-statusstalltyped matches GitHub's auto-generated slug for ### Typed Stall Payload (status.stall.typed) ✓

Diff: 1 file, +68/-0.

Follow-ups (out of scope for this PR)

• The global event stream (GET /v1/events) does NOT emit status.stall.typed — the typed variant is exclusively on the per-session stream. Pre-existing minor docs drift (session.stalled listed vs session_stall in code) is also untouched here — separate cleanup PR if Boss wants it.
• recoveryExhausted field is computed locally by the dashboard from recoveryAttemptCount >= recoveryMaxAttempts, not server-emitted. No API surface to document.
• Channel-side fanout (Telegram/Slack/Email) currently receives legacy status.stall with free-form detail; a follow-up PR can route meta: toChannelFanoutPayload(payload) through SessionEventPayload.meta for typed channels. Not blocking — F-9 close scope is the SSE path.